home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / commtc2.zip / COMM_TC2.DOC < prev   
Text File  |  1993-01-04  |  11KB  |  291 lines
  1.  
  2.        Comm_TC2.C Ver. 1.00, RS-232 Support for the IBM PC - Documention
  3.  
  4.                           Author:  Kevin R. Bulgrien
  5.                                    February, 1989
  6.  
  7.                             LeTourneau College
  8.                             Microcomputer Services
  9.                             P.O. Box 7001
  10.                             Longview, TX 75607
  11.  
  12.  
  13. INTRODUCTION
  14.  
  15. This utility is an answer to the many public domain serial port routines which
  16. I have acquired in the quest for good RS-232 support under Turbo Pascal. Unlike
  17. the others, this one works.  Not only does it work, but it also allows you to
  18. use both COM1 and COM2 at the same time.  Designed to be relatively simple and
  19. easy to use, I hope many will benefit from it.
  20.  
  21. This code works under Turbo C.  While it was written for Turbo C 2.0, it will
  22. probably also work for older versions. For functionally equivalent routines
  23. which work under Turbo Pascal 3.0, or 4.0 and 5.0., look for COMM_TP3 or
  24. COMM_TP4.
  25.  
  26.  
  27. DISTRIBUTION POLICY
  28.  
  29. This package may be used in any application without restriction, although I do
  30. ask that it is not distributed in a modified form unless you give credit where
  31. credit is due.  This document must always accompany the software as well.  The
  32. files which make up this package are called COMM_TC2.C and COMM_TC2.DOC.
  33.  
  34.  
  35. CREDITS
  36.  
  37. Credit for this product must go to the various authors who showed me that if I
  38. wanted something that worked, I would have to write it myself - I won't bother
  39. to mention their names.  The most credit, however, must go to the book "Systems
  40. Software Tools" by Ted J. Biggerstaff.  I was amazed to find a book that so
  41. clearly outlined the IBM PC interrupt and serial port hardware.  The world of
  42. IBM PC technical information is a desert, and this book is a rare oasis in the
  43. midst of it.
  44.  
  45.  
  46. FEATURES
  47.  
  48.  - Interrupt driven receive routine
  49.  - Easily expandable interrupt routine
  50.  - Uninstalls the interrupt handlers on abnormal program termination
  51.  - Carrier Detect monitoring for modem support
  52.  - COM1 & COM2 simultaneously supported
  53.  - Example TTY and Port Setup routines included
  54.  - Easy to use even if you don't understand how it works
  55.  - Turbo C 2.0 compatible source code
  56.  - The price tag reads "FREE"
  57.  
  58.  
  59. DISCLAIMER
  60.  
  61. While the author has extensively tested the routines in this package, he will
  62. not be held responsible for any consequence arising from the use thereof.  It
  63. is the responsibility of the user to determine whether or not the enclosed
  64. routines will satisfactorily perform the required functions.
  65.  
  66.  
  67. GETTING STARTED - DOES IT REALLY WORK?
  68.  
  69. If you want to prove that these routines really work, just run the program as
  70. it is distributed.  What you will see is a crude terminal emulation program
  71. that is capable of receiving information from both COM ports at the same time.
  72. The screen echoes data from the "logged" COM port and buffers the data from
  73. the other port.  When the other COM port is logged, the buffered data is sent
  74. to the screen.  Also provided is a setup routine that lets you select a baud
  75. rate from 110 to 38400.  The other protocol attributes are also selectable.
  76.  
  77. You will quickly notice that the screen I/O for the terminal emulation barely
  78. keeps up with a 1200 baud transmission due to the slowness of the built-in
  79. Turbo C 'putch' function.  Obviously, you should find a faster method to write
  80. character data if you are going to use the screen very much.
  81.  
  82.  
  83. SETTING COMM_TC2 UP TO USE IN YOUR OWN PROGRAMS
  84.  
  85. In order to use the serial routines, you may remove all of the extra code that
  86. is included for the TTY example routines.  It is not important for you to
  87. understand how the routines work, but the following declarations are not
  88. optional and are required for normal RS-232 operation:
  89.  
  90.      #include <dos.h>
  91.      #include <bios.h>
  92.      #include <stdio.h>
  93.      #include <stdlib.h>
  94.  
  95.      #define MaxSize 512
  96.  
  97.      enum BaudType {B110,B150,B300,B600,B1200,B2400,B4800,B9600,B19200,B38400};
  98.      enum ParityType { None, Odd, Null, Even, MarkOff, Mark, SpaceOff, Space };
  99.      enum Boolean { FALSE, TRUE };
  100.  
  101.      typedef unsigned char byte;
  102.      typedef unsigned int word;
  103.  
  104.      typedef struct
  105.                {
  106.                  word THR;
  107.                  word RHR;
  108.                  word DLL;
  109.                  word IER;
  110.                  word DLM;
  111.                  word IIR;
  112.                  word LCR;
  113.                  word MCR;
  114.                  word LSR;
  115.                  word MSR; } INS8250 [2];
  116.  
  117.      typedef struct
  118.                {
  119.                  byte Baud;
  120.                  byte Parity;
  121.                  byte Stop;
  122.                  byte Bits;  } ComSettingsType [2];
  123.  
  124.      const INS8250 RS232 = {
  125.                              { 0x3F8, 0x3F8, 0x3F8, 0x3F9, 0x3F9,
  126.                                0x3FA, 0x3FB, 0x3FC, 0x3FD, 0x3FE
  127.                              },
  128.                              { 0x2F8, 0x2F8, 0x2F8, 0x2F9, 0x2F9,
  129.                                0x2FA, 0x2FB, 0x2FC, 0x2FD, 0x2FE
  130.                              }
  131.                            };
  132.  
  133.      void interrupt (*OldIntVector [2]) ();
  134.      enum Boolean IntInstalled [2];
  135.      word InHead [2], InTail [2];
  136.      ComSettingsType ComSettings;
  137.      byte InBuffer [2] [MaxSize];
  138.      enum Boolean Carrier [2];
  139.      word MaxPorts;
  140.  
  141.      void SetupRS232(byte Com,byte Baud,byte Parity,byte StopBits,byte DataBits)
  142.      void interrupt IntHandler ()
  143.      void InstallInt (byte Com)
  144.      void RemoveInt (byte Com)
  145.      atexit_t RemoveIntOnExit (void)
  146.  
  147. The following declarations are optional in that you can write your own routines
  148. to actually send and receive RS-232 information in the form that you wish to
  149. send it.  They are not optional if you do not write your own replacements.
  150.  
  151.      void WriteCOM (byte Com, byte *DataPtr)
  152.      byte ReadCOM (byte Com)
  153.  
  154. These routines are relevant only to the TTY emulation, but you may be able to
  155. use them to better understand how to use the actual port routines:
  156.  
  157.      void SetUpPort (byte Com)
  158.      void TTY (enum Boolean LocalEcho)
  159.  
  160. The main program MUST include the following code as it will cause the program
  161. to safely remove the interrupt handlers no matter how the program terminates:
  162.  
  163.      main ()
  164.      {
  165.        atexit ((atexit_t) RemoveIntOnExit);
  166.        IntInstalled [0] = FALSE;
  167.        IntInstalled [1] = FALSE;
  168.  
  169.        /* MaxPorts provides error checking in some of the required functions */
  170.  
  171.        MaxPorts = (biosequip () & 0x0E00) >> 9;
  172.  
  173.        /* The rest of your program body goes here */
  174.      }
  175.  
  176.  
  177. HOW TO USE THE INTERRUPT HANDLERS IN YOUR PROGRAM
  178.  
  179. Important note:  Never compile interrupt handlers with the stack checking code
  180.                  enabled.  Doing so will cause the program to crash every time
  181.                  the interrupt is invoked.
  182.  
  183. At any time you may invoke SetupRS232 to change the settings of the COM ports.
  184. Unless you are sure the port is already set up correctly, you should invoke
  185. SetupRS232 before you install the interrupt with InstallInt.
  186.  
  187. You may install either COM1, COM2 or both with InstallInt at any time and in
  188. any order.
  189.  
  190. You may uninstall either COM1, COM2 or both with RemoveInt at any time and in
  191. any order.
  192.  
  193. To read data that has come in from the port, one of the following is required:
  194.  
  195.      1) byte ReadCOM (byte Com)
  196.  
  197.         where Com is 0 or 1 for COM1 or COM2.  If no data is available, this
  198.         routine waits until it arrives.
  199.  
  200.  
  201.      2) disable ();
  202.         DataReady = (InTail [CurrentCom] != InHead [CurrentCom]);
  203.         enable ();
  204.  
  205.         where DataReady is a user defined enum Boolean that will be TRUE (1) if
  206.         data is waiting in the buffer or FALSE (0) if no data is waiting.
  207.  
  208.         disable ();
  209.         Buffer [0] = InBuffer [CurrentCom] [InHead [CurrentCom]];
  210.         InHead [CurrentCom] = (InHead [CurrentCom] + 1) % MaxSize;
  211.         enable ();
  212.  
  213.         where Buffer is a user defined pointer to an array of char that will
  214.         contain the next item in the buffer IF AND ONLY IF DateReady is TRUE.
  215.         The item is removed from the buffer with the statement following the
  216.         assignment.  A null does not terminate the character received.
  217.  
  218.         NEVER omit the disable() and enable() statements from these program
  219.         fragments. To do so would cause the program to operate unpredicatably.
  220.  
  221. To write data to the port, use one of the following methods:
  222.  
  223.      1) void WriteCOM (byte Com, byte *DataPtr)
  224.  
  225.         where Com is the 0 or 1 for COM1 or COM2 and DataPtr is a pointer to
  226.         string data to be sent to the port.  This routine will pause until all of
  227.         the data has been sent.  The data must end with a null character.
  228.  
  229.      2) PortReady = ((inportb (RS232 [Com].LSR) & 0x20) = 0x20);
  230.  
  231.         where PortReady is a user defined enum Boolean variable which will be
  232.         TRUE (1) if the port Transmitter Holding Register is ready for a
  233.         character to send to the port.
  234.  
  235.         PortReady = PortReady && ((inportb (RS232 [Com].MSR) & 0x30) = 0x30);
  236.  
  237.         This statement allows you to see if the CTS and DTR lines indicate that
  238.         the other serial device is ready to receive data.  It may be omitted if
  239.         you do not want to check these lines.
  240.  
  241.         disable ();
  242.         outportb (RS232 [Com].LCR, inportb (RS232 [Com].LCR) & 0x7F;
  243.         outportb (RS232 [Com].THR, *DataPtr);
  244.         enable ();
  245.  
  246.         where DataPtr is a user defined pointer to an array of char that
  247.         contains a character to send to the port.  PortReady MUST be TRUE
  248.         before placing this data in the Transmitter Holding Register otherwise
  249.         the previous data item will be lost.
  250.  
  251.         NEVER omit the disable() and enable() statements from these program
  252.         fragments. To do so would cause the program to operate unpredicatably.
  253.  
  254.  
  255. SUPPORT
  256.  
  257. User support may be obtained by contacting me via the LeTourneau College BBS
  258. at (214) 237-2742.  The BBS runs 24 hours a day and accepts calls at 300, 1200,
  259. and 2400 baud.  Since I am the SysOp of this board, this is the fastest way to
  260. reach me.  My GEnie mail address is K.BULGRIEN, but money being at a premium,
  261. I do not always check in on a regular basis.  I may also be reached during
  262. business hours at (214) 753-0231 ext. 352.
  263.  
  264. Support will be limited to clarification of the routines I wrote.  I will not
  265. debug your routines or enhance my routines for your specific application.
  266.  
  267.  
  268. UPDATES
  269.  
  270. I will place updates of the enclosed routines on LeTourneau College BBS at
  271. (214) 237-2742.  The BBS runs 24 hours a day and accepts calls at 300, 1200,
  272. and 2400 baud.
  273.  
  274. I will also place updates in the BORLAND RT on the GEnie information service.
  275.  
  276. Possible updates may include:
  277.  
  278.      1) An interrupt driven transmitter
  279.      2) More complete support of the Modem Status interrupt
  280.      3) Support of the Line Status interrupt
  281.      4) Support additional COM ports
  282.      5) Miscellaneous enhancements
  283.      6) Bug fixes
  284.  
  285.  
  286. VERSION HISTORY
  287.  
  288.  1.00  11/88  The original version placed in the Borland Roundtable on GEnie.
  289.  
  290. THE END
  291.